Aspects Overview
What Are Aspects?
Aspects are JavaScript files that Candescent dynamically injects into the Digital Banking platform at runtime. They allow partners and FIs to customize the user experience by manipulating the page's DOM — adding widgets, modifying elements, or integrating third-party services directly within the banking interface.
Aspects are supported on both web and mobile, but the execution model differs significantly between platforms.
Web vs. Mobile
| Concern | Web | Mobile |
|---|---|---|
| How Aspects run | Injected directly into the DOM | Rendered inside a native WebView |
| Interaction level | Full DOM access and manipulation | Overlay only |
| Delivery format | Plain .js file | Full .html document loaded into a WebView |
| Script loading | dbk.loadScript(url) (platform utility) | document.createElement('script') (manual) |
| Authentication | fetch() with session cookies using OIDC | Native bridge (tokenApiDetails) → apiToken:ready event |
| Layout management | CSS only | sizeAndLocation bridge to negotiate with native app |
| Widget state tracking | Not needed | MutationObserver → condenseWindow / expandWindow |
| Native bridge APIs | Not used | iOS: window.webkit.messageHandlers, Android: JSBridge |
For the full implementation details for each platform, see the technical references:
Aspect Categories
Aspects fall into two categories based on whether they need to know who the logged-in user is.
1. Context-less Aspects
A context-less Aspect runs independently of the user's identity or session. It does not need any user-specific information.
Use cases:
- Injecting promotional banners or announcements
- Adding anonymous chat widgets
- Web Only: Modifying HTML/DOM elements (styling, tooltips, layout adjustments)
Simple example:
alert('Hello World!');
2. Context-aware Aspects
A context-aware Aspect operates using the logged-in user's information. This is necessary for integrations like personalized chat, user-specific widgets, or services that need to verify identity.
How you obtain user context depends on the platform:
| Platform | Methods | Details |
|---|---|---|
| Web | Global Variables, OIDC Authorization Code | See below |
| Mobile | Global Variables (GUID only), OIDC via Native Bridge | See below and Mobile Technical Reference |
Global Variables
After a user logs in, the platform stores basic user information in browser-accessible global variables. Your Aspect can read these using dbk.sessionInfo().
| Field | Method | Web | Mobile |
|---|---|---|---|
| User GUID | dbk.sessionInfo().userGuid | Available | Available |
| Full Name | dbk.sessionInfo().userFullName | Available | Not available |
const guid = dbk.sessionInfo().userGuid;
const name = dbk.sessionInfo().userFullName; // web only
Global variable data is automatically cleared on logout. Because this data is accessible to any script in the DOM, use it only for cross-validation or display purposes — never as the sole source of trust for sensitive operations.
OIDC Authorization Code
For integrations that require verified, secure user identity, use the OIDC approach. The Aspect requests an authorization code from the platform, then your backend exchanges it for a token containing user claims. Both platforms support OIDC, but the mechanism differs:
| Platform | How OIDC Works |
|---|---|
| Web | The Aspect calls the OIDC token endpoint directly using fetch() with session cookies |
| Mobile | The Aspect delegates the OIDC token endpoint call to the native app via the tokenApiDetails bridge, since session cookies are not available in the WebView |
- Web: See the Web Technical Reference for endpoint details
- Mobile: See the Mobile Technical Reference for the native bridge pattern
- OIDC background: See the OIDC Integration guide for the Authorization Code Flow
How to Choose
Web
| Question | Context-less | Context-aware (Global Var) | Context-aware (OIDC) |
|---|---|---|---|
| Does the script need user identity? | No | Yes | Yes |
| Is security-sensitive identity verification required? | No | No | Yes |
| Does the script call a backend API? | Optional | Optional | Yes |
| Complexity | Low | Low | Medium |
Mobile
| Question | Context-less | Context-aware (Native Bridge) |
|---|---|---|
| Does the script need user identity? | No | Yes |
| Does the script call a backend API? | Optional | Yes |
| Complexity | Low | Medium |
What FIs Need to Provide
To enable an Aspect, the FI provides:
- The JavaScript file (or URL to it) with vendor-specific configuration
- The category (context-less or context-aware) and method (global variable or OIDC)
- The target platform (web, mobile, or both)
Next Steps
- Web Technical Reference — Endpoints, OIDC token flow, and code examples for web Aspects
- Mobile Technical Reference — WebView execution, native bridges, and layout management for mobile Aspects
- Web Examples — Complete working examples for web
- Mobile Examples — Complete working examples for mobile
- FAQ — Common questions from FIs and partners
- Submissions — Submit an Aspect through the Developer Console
- OIDC Integration Guide — Full OIDC background (if your Aspect uses the OIDC method)